Clarify `sink` behaviour in implicit subscription model by PedroDiez · Pull Request #680 · camaraproject/Commonalities

PedroDiez · 2026-07-24T14:48:38Z

What type of PR is this?

enhancement/feature

What this PR does / why we need it:

Formalises the behaviour for sink handling in the implicit-subscription model: when a consumer provides a sink in the request, the API provider must either deliver events or reject the request with an error — silently creating the resource without notifications is no longer permitted.

Changes

documentation/CAMARA-API-Event-Subscription-and-Notification-Guide.md

Added a Sink delivery paragraph to §2.1 stating:
- Implementations SHOULD support event delivery when sink is provided.
- If delivery is not supported, the request MUST be rejected with 422 EVENT_NOTIFICATIONS_NOT_SUPPORTED and the resource MUST NOT be created.
- Consumers can retry without sink (e.g. fall back to polling).

artifacts/common/CAMARA_event_common.yaml

Added a new example GENERIC_422_EVENT_NOTIFICATIONS_NOT_SUPPORTED

artifacts/api-templates/sample-implicit-events.yaml

Updated POST /resources description to document the 422 EVENT_NOTIFICATIONS_NOT_SUPPORTED error path.
Updated CreateResource.sink description to clarify that omitting sink skips notifications, and when an API provider doesn't support notification delivery at all when sink is signalled within the request, an error is returned and resource is not created.
Updated Resource.sink description to reflect that sink is echoed only when delivery is accepted and active.
Added EVENT_NOTIFICATIONS_NOT_SUPPORTED to the 422 response enum and added a corresponding example (referenced to new added CAMARA_Event_common.yaml example aforementioned) with an actionable error message

artifacts/testing/sample-implicit-events-template.feature

Added test scenario for the case event notification delivery is implemented by the API provider
Added test scenario for the case the API provider doesn't support event notification delivery at all

Which issue(s) this PR fixes:

Fixes #628

Does this PR introduce a breaking change?

Yes
No
Not clear behaviour so far so both allowing the resorce creation without notifications delivery as well as generating an error would be acceptable

NOTE: Today an implementation may accept sink, create the resource, and simply not send events; nothing forbids it. After this PR that is no longer allowed. Whether to document the new 422 is then each API's own decision: an API that wants to allow implementations without notification delivery adds it — a breaking change per §7.4 of the Design Guide, so a major version — while an API that expects every implementation to deliver events adds nothing and stays as it is.(camaraproject/QualityOnDemand#556 tracks that decision for QoD).

This PR unifies behaviour and introduces a new Error Code 422 EVENT_NOTIFICATIONS_NOT_SUPPORTED, so backwards compatibility is not kept

Special notes for reviewers:

Changelog input

 clarify `sink` behaviour in implicit subscription model

Additional documentation

This section can be blank.

docs

bigludo7

LGTM

rartych · 2026-07-27T11:47:03Z

Additional test case in sample-implicit-events-template.feature can be considered to check the error response when event delivery is not supported.

PedroDiez · 2026-07-27T14:31:21Z

Additional test case in sample-implicit-events-template.feature can be considered to check the error response when event delivery is not supported.

Thanks @rartych! Good point

Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com>

…uide.md Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com>

bigludo7

LGTM
Thanks @PedroDiez for the reminder

hdamker

See a few suggestions below.

Two small things in the PR description, since it feeds the release notes:

The Changes list doesn't mention the added test scenario in artifacts/testing/sample-implicit-events-template.feature.
"providing an unsupported sink returns an error" (in the CreateResource.sink bullet) sounds like the existing 400 INVALID_SINK / INVALID_PROTOCOL / INVALID_CREDENTIAL cases, which this PR doesn't change. The new code is for a different case: the provider doesn't support notification delivery at all.

On the breaking change I agree, and I think the PR should say who has to act on it. Today an implementation may accept sink, create the resource, and simply not send events; nothing forbids it. After this PR that is no longer allowed. Whether to document the new 422 is then each API's own decision: an API that wants to allow implementations without notification delivery adds it — a breaking change per §7.4 of the Design Guide, so a major version — while an API that expects every implementation to deliver events adds nothing and stays as it is (camaraproject/QualityOnDemand#556 tracks that decision for QoD). Worth saying so in §2.1, so the new text isn't read as requiring the error in every API offering the pattern.

Co-authored-by: Herbert Damker <herbert.damker@telekom.de>

…uide.md Co-authored-by: Herbert Damker <herbert.damker@telekom.de>

Co-authored-by: Herbert Damker <herbert.damker@telekom.de>

…uide.md Co-authored-by: Herbert Damker <herbert.damker@telekom.de>

PedroDiez · 2026-07-29T15:07:49Z

See a few suggestions below.

Two small things in the PR description, since it feeds the release notes:

The Changes list doesn't mention the added test scenario in artifacts/testing/sample-implicit-events-template.feature.

"providing an unsupported sink returns an error" (in the CreateResource.sink bullet) sounds like the existing 400 INVALID_SINK / INVALID_PROTOCOL / INVALID_CREDENTIAL cases, which this PR doesn't change. The new code is for a different case: the provider doesn't support notification delivery at all.

On the breaking change I agree, and I think the PR should say who has to act on it. Today an implementation may accept sink, create the resource, and simply not send events; nothing forbids it. After this PR that is no longer allowed. Whether to document the new 422 is then each API's own decision: an API that wants to allow implementations without notification delivery adds it — a breaking change per §7.4 of the Design Guide, so a major version — while an API that expects every implementation to deliver events adds nothing and stays as it is (camaraproject/QualityOnDemand#556 tracks that decision for QoD). Worth saying so in §2.1, so the new text isn't read as requiring the error in every API offering the pattern.

Hi @hdamker, please take a look to the updates

hdamker

Thanks for the updates, the suggestions are all in. Four small ones below, plus one point that is not code.

GENERIC_422_EVENT_NOTIFICATIONS_NOT_SUPPORTED is the only example in CreateResourceUnprocessableEntity422 defined inline; the other five reference the shared examples. Under the consumption model introduced by #665 (define the response locally, reference the shared examples) the new example would be added to components/examples in CAMARA_event_common.yaml and referenced from here, as GENERIC_422_PRIVATE_KEY_JWT_NOT_CONFIGURED is. That also gives APIs adopting the implicit subscription pattern something to reference instead of copying the example. The intro comment of the 422 block in that section is scoped to subscription creation today, so it would need to cover the implicit model as well.

…uide.md Co-authored-by: Herbert Damker <herbert.damker@telekom.de>

Co-authored-by: Herbert Damker <herbert.damker@telekom.de>

hdamker

LGTM - thanks for also adding the example to CAMARA_event_common.yaml

(corrected the filename in the PR description, and deleted an invisible U+200E formatting character in another quoted path)

rartych

LGTM

Thank you @PedroDiez

bigludo7

LGTM - Thanks Pedro

PedroDiez · 2026-07-31T09:12:01Z

@eric-murray, please can you review this PR?

Clarify sink behaviour in implicit subscription model

1fe7e82

PedroDiez requested review from bigludo7, eric-murray, jlurien and rartych as code owners July 24, 2026 14:48

PedroDiez self-assigned this Jul 24, 2026

PedroDiez requested a review from hdamker July 24, 2026 14:49

bigludo7 previously approved these changes Jul 24, 2026

View reviewed changes

rartych reviewed Jul 27, 2026

View reviewed changes

Comment thread artifacts/api-templates/sample-implicit-events.yaml Outdated

rartych reviewed Jul 27, 2026

View reviewed changes

Comment thread documentation/CAMARA-API-Event-Subscription-and-Notification-Guide.md Outdated

Update artifacts/api-templates/sample-implicit-events.yaml

4443491

Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com>

PedroDiez dismissed bigludo7’s stale review via 4443491 July 27, 2026 14:31

PedroDiez and others added 2 commits July 27, 2026 16:32

Update documentation/CAMARA-API-Event-Subscription-and-Notification-G…

92da74b

…uide.md Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com>

add_test_case_for_event_notifications_delivery_not_supported

f6ba3f5

PedroDiez requested review from bigludo7 and rartych July 27, 2026 14:46

bigludo7 previously approved these changes Jul 28, 2026

View reviewed changes

hdamker reviewed Jul 28, 2026

View reviewed changes

rartych mentioned this pull request Jul 28, 2026

Normalize artifact line endings and Gherkin formatting #678

Merged

2 tasks

merge_main

c04e908

PedroDiez dismissed bigludo7’s stale review via c04e908 July 29, 2026 12:16

PedroDiez and others added 7 commits July 29, 2026 14:18

Update artifacts/api-templates/sample-implicit-events.yaml error example

3c5d6b2

Co-authored-by: Herbert Damker <herbert.damker@telekom.de>

Update documentation/CAMARA-API-Event-Subscription-and-Notification-G…

fdf703f

…uide.md Co-authored-by: Herbert Damker <herbert.damker@telekom.de>

Update artifacts/testing/sample-implicit-events-template.feature

882a08c

Co-authored-by: Herbert Damker <herbert.damker@telekom.de>

Update documentation/CAMARA-API-Event-Subscription-and-Notification-G…

37267ef

…uide.md Co-authored-by: Herbert Damker <herbert.damker@telekom.de>

updates_in_events_guide_and_implict_events_template

d5aa592

clarification_for_adoption_of_this_behaviour

46ffaf0

add_test_scenario

b03468d

PedroDiez requested a review from hdamker July 29, 2026 15:07

hdamker reviewed Jul 29, 2026

View reviewed changes

PedroDiez and others added 6 commits July 30, 2026 11:19

Update documentation/CAMARA-API-Event-Subscription-and-Notification-G…

a814882

…uide.md Co-authored-by: Herbert Damker <herbert.damker@telekom.de>

Update documentation/CAMARA-API-Event-Subscription-and-Notification-G…

a60751b

…uide.md Co-authored-by: Herbert Damker <herbert.damker@telekom.de>

Update artifacts/api-templates/sample-implicit-events.yaml

714b98d

Co-authored-by: Herbert Damker <herbert.damker@telekom.de>

Update artifacts/testing/sample-implicit-events-template.feature

75c8bb9

Co-authored-by: Herbert Damker <herbert.damker@telekom.de>

add_new_error_in_CAMARA_Event_Common_components_examples

c2cda99

fix_linter

2abd04b

PedroDiez requested review from bigludo7 and hdamker July 30, 2026 10:14

hdamker approved these changes Jul 30, 2026

View reviewed changes

rartych approved these changes Jul 30, 2026

View reviewed changes

bigludo7 approved these changes Jul 30, 2026

View reviewed changes

Uh oh!

Conversation

PedroDiez commented Jul 24, 2026 • edited by hdamker Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What type of PR is this?

What this PR does / why we need it:

Which issue(s) this PR fixes:

Does this PR introduce a breaking change?

Special notes for reviewers:

Changelog input

Additional documentation

Uh oh!

bigludo7 left a comment

Choose a reason for hiding this comment

Uh oh!

rartych commented Jul 27, 2026

Uh oh!

Uh oh!

Uh oh!

PedroDiez commented Jul 27, 2026

Uh oh!

bigludo7 left a comment

Choose a reason for hiding this comment

Uh oh!

hdamker left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

PedroDiez commented Jul 29, 2026

Uh oh!

hdamker left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hdamker left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rartych left a comment

Choose a reason for hiding this comment

Uh oh!

bigludo7 left a comment

Choose a reason for hiding this comment

Uh oh!

PedroDiez commented Jul 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

PedroDiez commented Jul 24, 2026 •

edited by hdamker

Loading

hdamker left a comment •

edited

Loading

hdamker left a comment •

edited

Loading